package com.tbynet.jwp.service.impl;

import com.jfinal.aop.Inject;
import com.jfinal.kit.Ret;
import com.jfinal.kit.StrKit;
import com.jfinal.plugin.activerecord.Page;
import com.tbynet.jwp.framework.aop.Aop;
import com.tbynet.jwp.framework.core.JwpConstants;
import com.tbynet.jwp.framework.core.JwpService;
import com.tbynet.jwp.framework.bean.PageParams;
import com.tbynet.jwp.framework.bean.Permission;
import com.tbynet.jwp.framework.bean.Role;
import com.tbynet.jwp.framework.exception.BusinessException;
import com.tbynet.jwp.framework.kit.PassKit;
import com.tbynet.jwp.framework.kit.StringKit;
import com.tbynet.jwp.framework.kit.ValidateKit;
import com.tbynet.jwp.service.spi.UserManager;
import com.tbynet.jwp.model.Users;
import com.tbynet.jwp.model.Usermeta;
import com.tbynet.jwp.repository.spi.UserService;
import org.phprpc.util.AssocArray;
import org.phprpc.util.PHPSerializer;

import java.util.*;
import java.util.concurrent.TimeUnit;
import java.util.function.Supplier;

/**
 * 用户管理编排层 - 优化重构版
 *
 * 核心职责：
 * 1. 用户生命周期管理（注册、登录、更新、删除）
 * 2. 会话管理和权限控制
 * 3. 用户信息管理和查询
 * 4. 用户统计和通知
 *
 * 设计原则：
 * - 不包含任何SQL代码，只编排Service层方法
 * - 一个方法完成一个完整的业务用例
 * - 统一的事务管理和错误处理
 * - 支持性能监控和统计
 *
 * @author 佰亿互联
 * @version 3.1
 * @since 2025-11-04
 */
@Aop(UserManager.class)
public class UserServiceImpl extends JwpService implements UserManager {

    // ============ 业务常量 ============

    /** 保持登录状态的会话有效期（秒）- 1年 */
    private static final long KEEP_LOGIN_SECONDS = TimeUnit.DAYS.toSeconds(365);

    /** 默认登录会话有效期（秒）- 2小时 */
    private static final long DEFAULT_LOGIN_SECONDS = TimeUnit.HOURS.toSeconds(2);

    /** 最大登录尝试次数 - 防止暴力破解 */
    private static final int MAX_LOGIN_ATTEMPTS = 5;

    /** 会话滑动过期延长分钟数 */
    private static final long SESSION_EXTEND_MINUTES = 30;

    // ============ 缓存名称常量 ============

    /** 用户信息缓存名称 */
    private static final String USER_CACHE = "userCache";

    /** 登录尝试次数缓存名称 */
    private static final String LOGIN_ATTEMPTS_CACHE = "loginAttemptsCache";

    /** 用户统计缓存名称 */
    private static final String USER_STATS_CACHE = "userStatsCache";

    // ============ 用户状态常量 ============

    /** 用户激活状态 */
    private static final int USER_STATUS_ACTIVE = 0;

    /** 用户禁用状态 */
    private static final int USER_STATUS_INACTIVE = 1;

    // ============ 默认角色和配置 ============

    /** 默认用户角色 - 订阅者 */
    private static final String DEFAULT_USER_ROLE = "subscriber";

    /** 默认编辑器设置 - 启用富文本编辑 */
    private static final String DEFAULT_RICH_EDITING = "true";

    // ============ 错误码常量 ============

    /** 登录限制错误码 */
    private static final String ERROR_LOGIN_LIMITED = "LOGIN_LIMITED";

    /** 无效凭证错误码 */
    private static final String ERROR_INVALID_CREDENTIALS = "INVALID_CREDENTIALS";

    /** 用户状态异常错误码 */
    private static final String ERROR_USER_INACTIVE = "USER_INACTIVE";

    /** 会话保存失败错误码 */
    private static final String ERROR_SESSION_SAVE_FAILED = "SESSION_SAVE_FAILED";

    /** 用户名已存在错误码 */
    private static final String ERROR_USERNAME_EXISTS = "USERNAME_EXISTS";

    /** 邮箱已存在错误码 */
    private static final String ERROR_EMAIL_EXISTS = "EMAIL_EXISTS";

    /** 保存失败错误码 */
    private static final String ERROR_SAVE_FAILED = "SAVE_FAILED";

    /** 用户不存在错误码 */
    private static final String ERROR_USER_NOT_FOUND = "USER_NOT_FOUND";

    /** 密码验证失败错误码 */
    private static final String ERROR_PASSWORD_VALIDATION_FAILED = "PASSWORD_VALIDATION_FAILED";

    // ============ 依赖注入 ============

    @Inject
    private UserService userService;

    // ============ 用户认证和会话管理 ============

    /**
     * 用户登录业务编排
     *
     * @param username 用户名或邮箱地址（必需）
     * @param password 用户密码（明文，必需）
     * @param keepLogin 是否保持登录状态（可选，默认false）
     * @param loginIp 用户登录IP地址（必需）
     * @param userAgent 用户浏览器代理信息（可选）
     * @return Ret 登录结果，包含会话信息和用户数据
     *         - 成功：包含sessionId、userInfo、maxAgeInSeconds
     *         - 失败：包含错误码和错误消息
     *
     * @example
     * <pre>{@code
     * Ret result = userManager.login("admin", "password123", true, "192.168.1.1", "Mozilla/5.0");
     * if (result.isOk()) {
     *     String sessionId = result.getStr(Users.sessionIdName);
     *     Users user = result.get(Users.loginUserCacheName);
     *     // 处理登录成功逻辑
     * } else {
     *     String errorMsg = result.getStr("msg");
     *     // 处理登录失败逻辑
     * }
     * }</pre>
     */
    public Ret login(final String username, final String password, final Boolean keepLogin,
                     final String loginIp, final String userAgent) {
        return executeWithAuthMonitoring("login", () -> {
            // 参数验证
            final Ret validationResult = validateLoginParams(username, password, loginIp);
            if (validationResult.isFail()) {
                return validationResult;
            }

            // 登录限制检查
            if (isLoginLimited(username)) {
                log.warn("登录限制触发，用户名: %s, IP: %s", StringKit.hideSensitiveInfo(username, 2, 2), loginIp);
                return buildBusinessError(ERROR_LOGIN_LIMITED, "登录尝试次数过多，请30分钟后再试");
            }

            // 用户查找和验证
            final Users user = findUserWithCache(username);
            if (user == null || !validatePassword(password, user.getUserPass())) {
                recordLoginFailure(username, loginIp);
                log.warn("登录失败：用户名或密码错误，用户名: %s, IP: %s", StringKit.hideSensitiveInfo(username, 2, 2), loginIp);
                return buildBusinessError(ERROR_INVALID_CREDENTIALS, "用户名或密码错误");
            }

            // 用户状态检查
            if (!isUserActive(user)) {
                log.warn("登录失败：用户状态异常，用户ID: %s, 用户名: %s", user.getID(), StringKit.hideSensitiveInfo(username, 2, 2));
                return buildBusinessError(ERROR_USER_INACTIVE, "用户状态异常，无法登录");
            }

            // 创建用户会话
            final Ret loginResult = createUserSession(user,
                    Boolean.TRUE.equals(keepLogin), loginIp, userAgent);
            if (loginResult.isOk()) {
                clearLoginFailureRecords(username);
                updateUserLoginStats(user, loginIp);
                log.info("用户登录成功，用户ID: %s, 用户名: %s, IP: %s",
                        user.getID(), StringKit.hideSensitiveInfo(username, 2, 2), loginIp);
            }

            return loginResult;
        }, "username:" + StringKit.hideSensitiveInfo(username, 2, 2));
    }

    /**
     * 用户登出业务编排
     *
     * @param sessionId 用户会话ID（必需）
     * @return Ret 登出结果
     *         - 成功：包含成功消息
     *         - 失败：包含错误信息
     *
     * @example
     * <pre>{@code
     * Ret result = userManager.logout("session-id-123");
     * if (result.isOk()) {
     *     System.out.println("登出成功");
     * }
     * }</pre>
     */
    public Ret logout(final String sessionId) {
        return executeWithAuthMonitoring("logout", () -> {
            if (StrKit.isBlank(sessionId)) {
                return buildParamError("sessionId", "会话ID不能为空");
            }

            // 从缓存获取用户信息
            final Users user = cache.getCache(Users.loginUserCacheName, sessionId, null);
            if (user != null) {
                // 从数据库删除会话
                removeUserSessionFromDatabase(user, sessionId);
            }

            // 从缓存删除会话
            cache.removeCache(Users.loginUserCacheName, sessionId);

            log.info("用户登出成功，会话ID: %s", StringKit.hideSensitiveInfo(sessionId, 8, 4));
            return buildSuccess("登出成功", null);
        }, "sessionId:" + StringKit.hideSensitiveInfo(sessionId, 8, 4));
    }

    /**
     * 用户注册业务编排
     *
     * @param username 用户名（必需）
     * @param password 密码（明文，必需）
     * @param email 邮箱（必需）
     * @param nickname 昵称（可选）
     * @param registerIp 注册IP（必需）
     * @param userAgent 用户代理（可选）
     * @return Ret 注册结果
     *         - 成功：包含用户ID
     *         - 失败：包含错误码和错误消息
     *
     * @example
     * <pre>{@code
     * Ret result = userManager.register("newuser", "password123",
     *     "user@example.com", "昵称", "192.168.1.1", "Mozilla/5.0");
     * if (result.isOk()) {
     *     Long userId = result.getAs("data");
     *     // 处理注册成功逻辑
     * }
     * }</pre>
     */
    public Ret register(final String username, final String password, final String email,
                        final String nickname, final String registerIp, final String userAgent) {
        return executeWithAuthMonitoring("register", () -> {
            // 参数验证
            final Ret validationResult = validateRegisterParams(username, password, email);
            if (validationResult.isFail()) {
                return validationResult;
            }

            // 检查用户是否存在
            if (userService.isUserLoginExists(username)) {
                return buildBusinessError(ERROR_USERNAME_EXISTS, "用户名已存在");
            }
            if (userService.isEmailExists(email)) {
                return buildBusinessError(ERROR_EMAIL_EXISTS, "邮箱已被使用");
            }

            // 创建用户对象
            final Users user = createUserInstance(username, password, email, nickname);

            // 设置默认元数据
            final List<Usermeta> metas = createDefaultUserMetas(user);

            // 在事务中保存用户信息
            final boolean success = executeInTransaction(() ->
                    userService.save(user) && saveUserMetas(user, metas)
            );

            if (success) {
                // 异步发送欢迎通知
                sendWelcomeNotificationAsync(user);
                log.info("用户注册成功，用户ID: %s, 用户名: %s", user.getID(), StringKit.hideSensitiveInfo(username, 2, 2));
                return buildSuccess("注册成功", user.getID());
            } else {
                log.error("用户注册失败，保存数据异常，用户名: %s", StringKit.hideSensitiveInfo(username, 2, 2));
                return buildBusinessError(ERROR_SAVE_FAILED, "注册失败，请重试");
            }
        }, "username:" + StringKit.hideSensitiveInfo(username, 2, 2));
    }

    // ============ 用户信息管理 ============

    /**
     * 创建用户业务编排
     *
     * @param user 用户基本信息（必需）
     * @param metas 用户元数据列表（可选）
     * @return Ret 创建结果
     *         - 成功：包含用户ID
     *         - 失败：包含错误信息
     *
     * @example
     * <pre>{@code
     * Users user = new Users();
     * user.setUserLogin("testuser");
     * user.setUserEmail("test@example.com");
     *
     * List<Usermeta> metas = new ArrayList<>();
     * metas.add(new Usermeta().setMetaKey("key").setMetaValue("value"));
     *
     * Ret result = userManager.createUser(user, metas);
     * if (result.isOk()) {
     *     Long userId = result.getAs("data");
     * }
     * }</pre>
     */
    public Ret createUser(final Users user, final List<Usermeta> metas) {
        return executeWithUserMonitoring("createUser", () -> {
            // 参数验证
            final Ret validationResult = validateCreateUserParams(user);
            if (validationResult.isFail()) {
                return validationResult;
            }

            // 设置默认值
            setUserDefaultValues(user);

            // 在事务中执行创建操作
            final boolean success = executeInTransaction(() ->
                    processUserCreation(user, metas)
            );

            return handleUserCreationResult(success, user);
        }, user != null ? String.valueOf(user.getID()) : "unknown");
    }

    /**
     * 更新用户信息业务编排
     *
     * @param user 更新后的用户信息（必需）
     * @param metas 更新后的元数据列表（可选）
     * @return Ret 更新结果
     *         - 成功：包含用户ID
     *         - 失败：包含错误信息
     *
     * @example
     * <pre>{@code
     * Users user = userManager.getUserDetail(1L);
     * user.setDisplayName("新显示名称");
     *
     * Ret result = userManager.updateUser(user, null);
     * if (result.isOk()) {
     *     System.out.println("更新成功");
     * }
     * }</pre>
     */
    public Ret updateUser(final Users user, final List<Usermeta> metas) {
        return executeWithUserMonitoring("updateUser", () -> {
            // 参数验证
            final Ret validationResult = validateUpdateUserParams(user);
            if (validationResult.isFail()) {
                return validationResult;
            }

            // 获取旧用户数据
            final Users oldUser = getUserWithCache(user.getID());
            if (oldUser == null) {
                return buildBusinessError(ERROR_USER_NOT_FOUND, "用户不存在");
            }

            // 在事务中执行更新操作
            final boolean success = executeInTransaction(() ->
                    processUserUpdate(user, metas)
            );

            return handleUserUpdateResult(success, user, oldUser);
        }, user != null ? String.valueOf(user.getID()) : "unknown");
    }

    /**
     * 删除用户业务编排
     *
     * @param userId 用户ID（必需）
     * @return Ret 删除结果
     *         - 成功：包含成功消息
     *         - 失败：包含错误信息
     *
     * @example
     * <pre>{@code
     * Ret result = userManager.deleteUser(1L);
     * if (result.isOk()) {
     *     System.out.println("删除成功");
     * }
     * }</pre>
     */
    public Ret deleteUser(final Object userId) {
        return executeWithUserMonitoring("deleteUser", () -> {
            // 参数验证
            if (userId == null) {
                return buildParamError("userId", "用户ID不能为空");
            }

            // 验证用户存在性
            if (!userService.existsById(userId)) {
                return buildBusinessError(ERROR_USER_NOT_FOUND, "用户不存在");
            }

            // 在事务中执行删除操作
            final boolean success = executeInTransaction(() ->
                    deleteUserInTransaction(userId)
            );

            return handleUserDeletionResult(success, userId);
        }, String.valueOf(userId));
    }

    // ============ 用户查询和搜索 ============

    /**
     * 搜索用户业务编排
     *
     * @param pageNumber 页码（必需）
     * @param pageSize 每页大小（必需）
     * @param keyword 搜索关键词（可选）
     * @return Page<Users> 搜索结果分页对象
     *
     * @example
     * <pre>{@code
     * Page<Users> result = userManager.searchUsers(1, 20, "admin");
     * List<Users> users = result.getList();
     * long total = result.getTotalRow();
     * }</pre>
     */
    public Page<Users> searchUsers(final int pageNumber, final int pageSize, final String keyword) {
        if(!ValidateKit.isValidPageParams(pageNumber, pageSize)) {
            throw new BusinessException("无效的分页参数");
        }

        return executeWithPageMonitoring("searchUsers", () -> {
            // 参数验证和默认值处理
            final PageParams pageParams = PageParams.of(pageNumber, pageSize);

            // 生成缓存键
            final String cacheKey = generateUserSearchCacheKey(keyword, pageParams);
            final String countCacheKey = generateUserSearchCountCacheKey(keyword);

            log.debug("搜索用户，关键词: %s, 缓存键: %s", StringKit.hideSensitiveInfo(keyword, 3, 3), cacheKey);

            // 尝试从缓存获取
            final Page<Users> cachedPage = getCachedUserPage(cacheKey, countCacheKey, pageParams);
            if (cachedPage != null) {
                log.debug("用户搜索缓存命中，关键词: %s", StringKit.hideSensitiveInfo(keyword, 3, 3));
                return cachedPage;
            }

            // 缓存未命中，从数据库查询
            final Page<Users> page = userService.search(
                    pageParams.getPageNumber(), pageParams.getPageSize(), keyword);

            // 处理并缓存结果
            return processAndCacheUserSearchResult(page, cacheKey, countCacheKey, keyword);
        }, "keyword:" + (keyword != null ? StringKit.hideSensitiveInfo(keyword, 3, 3) : "null"));
    }

    /**
     * 获取用户详情业务编排（带缓存）
     *
     * @param userId 用户ID（必需）
     * @return Users 用户详情对象，如果不存在返回null
     *
     * @example
     * <pre>{@code
     * Users user = userManager.getUserDetail(1L);
     * if (user != null) {
     *     String email = user.getUserEmail();
     *     String name = user.getDisplayName();
     * }
     * }</pre>
     */
    public Users getUserDetail(final Object userId) {
        return executeWithUserDetailMonitoring("getUserDetail", () -> {
            // 参数验证
            if (userId == null) {
                return null;
            }

            // 构建缓存键
            final String cacheKey = "user:" + userId;

            // 尝试从缓存获取
            final Users cachedUser = cache.getCache(USER_CACHE, cacheKey, null);
            if (cachedUser != null) {
                log.debug("用户详情缓存命中，用户ID: %s", userId);
                return cachedUser;
            }

            // 缓存未命中，从数据库查询并处理
            return processAndCacheUserDetail(userId, cacheKey);
        }, String.valueOf(userId));
    }

    // ============ 会话和权限管理 ============

    /**
     * 用户会话验证业务编排
     *
     * @param sessionId 会话ID（必需）
     * @return Users 有效的用户对象，无效返回null
     *
     * @example
     * <pre>{@code
     * Users user = userManager.validateAndGetLoginUser("session-id-123");
     * if (user != null) {
     *     // 用户已登录且会话有效
     * } else {
     *     // 会话无效或已过期
     * }
     * }</pre>
     */
    public Users validateAndGetLoginUser(final String sessionId) {
        return executeWithUserDetailMonitoring("validateAndGetLoginUser", () -> {
            // 参数检查
            if (StrKit.isBlank(sessionId)) {
                return null;
            }

            // 缓存快速验证
            final Users user = cache.getCache(Users.loginUserCacheName, sessionId, null);
            if (user == null) {
                log.debug("会话验证失败：缓存中未找到会话，会话ID: %s", StringKit.hideSensitiveInfo(sessionId, 8, 4));
                return null;
            }

            // 数据库会话验证
            if (!validateSessionInDatabase(user, sessionId)) {
                // 数据库验证失败，清理缓存
                cache.removeCache(Users.loginUserCacheName, sessionId);
                return null;
            }

            // 延长会话有效期
            extendSessionExpiration(user, sessionId);

            return user;
        }, "sessionId:" + StringKit.hideSensitiveInfo(sessionId, 8, 4));
    }

    /**
     * 强制登出其他设备业务编排
     *
     * @param currentSessionId 当前会话ID（必需）
     * @return Ret 操作结果
     *         - 成功：包含成功消息
     *         - 失败：包含错误信息
     *
     * @example
     * <pre>{@code
     * Ret result = userManager.destroyOtherSessions("current-session-id");
     * if (result.isOk()) {
     *     System.out.println("其他设备已登出");
     * }
     * }</pre>
     */
    public Ret destroyOtherSessions(final String currentSessionId) {
        return executeWithAuthMonitoring("destroyOtherSessions", () -> {
            // 验证当前会话有效性
            final Users user = cache.getCache(Users.loginUserCacheName, currentSessionId, null);
            if (user == null) {
                return buildBusinessError(ERROR_USER_NOT_FOUND, "当前会话无效");
            }

            // 获取会话元数据
            final Usermeta sessionMeta = userService.getUserMeta(user.getID(), Usermeta.session_tokens);
            if (sessionMeta == null) {
                log.debug("登出其他设备：用户没有其他会话，用户ID: %s", user.getID());
                return buildSuccess("没有其他会话需要登出", null);
            }

            // 删除其他会话
            final boolean result = removeOtherSessions(sessionMeta, currentSessionId);
            return handleSessionOperationResult(result, user.getID());
        }, "sessionId:" + StringKit.hideSensitiveInfo(currentSessionId, 8, 4));
    }

    /**
     * 获取用户角色权限列表
     *
     * @param role 角色名称（必需）
     * @return List<String> 权限名称列表，如果角色不存在返回空列表
     *
     * @example
     * <pre>{@code
     * List<String> permissions = userManager.getUserPermissions("administrator");
     * if (permissions.contains("manage_users")) {
     *     // 用户有管理用户的权限
     * }
     * }</pre>
     */
    public List<String> getUserPermissions(final String role) {
        return executeWithStringListMonitoring("getUserPermissions", () -> {
            // 参数验证
            if (StrKit.isBlank(role)) {
                log.warn("获取用户权限列表失败：角色为空");
                return Collections.emptyList();
            }

            // 通过角色获取权限列表
            final List<String> permissions = new ArrayList<>();
            for (final Permission permission : Role.getPermissions(role)) {
                permissions.add(permission.getName());
            }

            log.debug("获取角色权限成功，角色: %s, 权限数量: %s", role, permissions.size());
            return permissions;

        }, role);
    }

    // ============ 私有方法：执行模板 ============

    /**
     * 执行认证操作并监控（返回Ret类型）
     */
    private Ret executeWithAuthMonitoring(final String methodName, final Supplier<Ret> operation, final String identifier) {
        return executeWithMonitoring(methodName, operation, identifier,
                e -> buildBusinessError(getAuthErrorCode(methodName), getAuthErrorMessage(methodName)));
    }

    /**
     * 执行用户操作并监控（返回Ret类型）
     */
    private Ret executeWithUserMonitoring(final String methodName, final Supplier<Ret> operation, final String identifier) {
        return executeWithMonitoring(methodName, operation, identifier,
                e -> buildBusinessError(getUserErrorCode(methodName), getUserErrorMessage(methodName)));
    }

    /**
     * 执行分页操作并监控（返回Page类型）
     */
    private Page<Users> executeWithPageMonitoring(final String methodName, final Supplier<Page<Users>> operation, final String identifier) {
        return executeWithMonitoring(methodName, operation, identifier,
                e -> new Page<>(Collections.emptyList(), 1, 10, 0, 0));
    }

    /**
     * 执行用户详情操作并监控（返回Users类型）
     */
    private Users executeWithUserDetailMonitoring(final String methodName, final Supplier<Users> operation, final String identifier) {
        return executeWithMonitoring(methodName, operation, identifier, e -> null);
    }

    /**
     * 执行列表操作并监控（返回List<String>类型）
     */
    private List<String> executeWithStringListMonitoring(final String methodName, final Supplier<List<String>> operation, final String identifier) {
        return executeWithMonitoring(methodName, operation, identifier,
                e -> new ArrayList<>());
    }

    /**
     * 通用执行监控模板
     */
    private <T> T executeWithMonitoring(final String methodName, final Supplier<T> operation,
                                        final String identifier, final java.util.function.Function<Exception, T> errorHandler) {
        final long startTime = System.currentTimeMillis();
        try {
            recordMethodCall(methodName);
            final T result = operation.get();
            logMethodPerformance(methodName, startTime, "SUCCESS");
            return result;
        } catch (Exception e) {
            recordMethodError(methodName);
            log.error("%s异常，标识: %s", methodName, identifier, e);
            return errorHandler.apply(e);
        }
    }

    // ============ 私有方法：参数验证 ============

    /**
     * 验证登录参数
     */
    private Ret validateLoginParams(final String username, final String password, final String loginIp) {
        if (StrKit.isBlank(username)) {
            return buildParamError("username", "用户名不能为空");
        }
        if (StrKit.isBlank(password)) {
            return buildParamError("password", "密码不能为空");
        }
        if (StrKit.isBlank(loginIp)) {
            return buildParamError("loginIp", "登录IP不能为空");
        }
        if (!StringKit.isValidLength(username, 3, 50)) {
            return buildParamError("username", "用户名长度应在3-50个字符之间");
        }
        if (!StringKit.isValidLength(password, 6, 100)) {
            return buildParamError("password", "密码长度不能少于6位");
        }
        return buildSuccess("参数验证通过", null);
    }

    /**
     * 验证注册参数
     */
    private Ret validateRegisterParams(final String username, final String password, final String email) {
        if (StrKit.isBlank(username)) {
            return buildParamError("username", "用户名不能为空");
        }
        if (StrKit.isBlank(password)) {
            return buildParamError("password", "密码不能为空");
        }
        if (StrKit.isBlank(email)) {
            return buildParamError("email", "邮箱不能为空");
        }
        if (!ValidateKit.validateEmail(email)) {
            return buildParamError("email", "邮箱格式不正确");
        }
        if (!StringKit.isValidLength(username, 3, 50)) {
            return buildParamError("username", "用户名长度应在3-50个字符之间");
        }
        if (!StringKit.isValidLength(password, 6, 100)) {
            return buildParamError("password", "密码长度不能少于6位");
        }
        return buildSuccess("参数验证通过", null);
    }

    /**
     * 验证创建用户参数
     */
    private Ret validateCreateUserParams(final Users user) {
        if (user == null) {
            return buildBusinessError("USER_NULL", "用户信息不能为空");
        }
        if (StrKit.isBlank(user.getUserLogin())) {
            return buildParamError("userLogin", "用户名不能为空");
        }
        if (StrKit.isBlank(user.getUserEmail())) {
            return buildParamError("userEmail", "邮箱不能为空");
        }
        if (!ValidateKit.validateEmail(user.getUserEmail())) {
            return buildParamError("userEmail", "邮箱格式不正确");
        }
        if (userService.isUserLoginExists(user.getUserLogin())) {
            return buildBusinessError(ERROR_USERNAME_EXISTS, "用户名已存在");
        }
        if (userService.isEmailExists(user.getUserEmail())) {
            return buildBusinessError(ERROR_EMAIL_EXISTS, "邮箱已被使用");
        }
        return buildSuccess("参数验证通过", null);
    }

    /**
     * 验证更新用户参数
     */
    private Ret validateUpdateUserParams(final Users user) {
        if (user == null || user.getID() == null) {
            return buildParamError("user", "用户信息和用户ID不能为空");
        }
        if (StrKit.isBlank(user.getUserLogin())) {
            return buildParamError("userLogin", "用户名不能为空");
        }
        if (StrKit.isBlank(user.getUserEmail())) {
            return buildParamError("userEmail", "邮箱不能为空");
        }
        if (!ValidateKit.validateEmail(user.getUserEmail())) {
            return buildParamError("userEmail", "邮箱格式不正确");
        }
        return buildSuccess("参数验证通过", null);
    }

    // ============ 私有方法：数据构建和默认值 ============

    /**
     * 创建用户实例
     */
    private Users createUserInstance(final String username, final String password, final String email, final String nickname) {
        final Users user = new Users();
        // 设置登录信息
        user.setUserLogin(username);
        user.setUserPass(PassKit.encrypt(password)); // 密码加密
        user.setUserEmail(email);

        // 设置显示信息
        user.setUserNicename(StrKit.isBlank(nickname) ? username : nickname);
        user.setDisplayName(StrKit.isBlank(nickname) ? username : nickname);

        // 设置系统信息
        user.setUserRegistered(new Date());
        user.setUserStatus(USER_STATUS_ACTIVE);

        return user;
    }

    /**
     * 设置用户默认值
     */
    private void setUserDefaultValues(final Users user) {
        if (user.getUserRegistered() == null) {
            user.setUserRegistered(new Date());
        }
        if (user.getUserStatus() == null) {
            user.setUserStatus(USER_STATUS_ACTIVE);
        }
        if (StrKit.isBlank(user.getUserNicename())) {
            user.setUserNicename(user.getUserLogin());
        }
        if (StrKit.isBlank(user.getDisplayName())) {
            user.setDisplayName(user.getUserLogin());
        }
    }

    /**
     * 创建默认用户元数据
     */
    private List<Usermeta> createDefaultUserMetas(final Users user) {
        final List<Usermeta> metas = new ArrayList<>();

        // 默认昵称元数据
        final Usermeta nicknameMeta = new Usermeta();
        nicknameMeta.setUserId(user.getID());
        nicknameMeta.setNickname(user.getUserNicename());
        metas.add(nicknameMeta);

        // 默认角色元数据
        final Usermeta roleMeta = new Usermeta();
        roleMeta.setUserId(user.getID());
        roleMeta.setRole(DEFAULT_USER_ROLE);
        metas.add(roleMeta);

        // 默认编辑器设置
        final Usermeta richEditingMeta = new Usermeta();
        richEditingMeta.setUserId(user.getID());
        richEditingMeta.setRichEditing(DEFAULT_RICH_EDITING);
        metas.add(richEditingMeta);

        log.debug("创建默认用户元数据完成，用户ID: %s, 元数据数量: %s", user.getID(), metas.size());
        return metas;
    }

    // ============ 私有方法：业务处理核心 ============

    /**
     * 处理用户创建流程
     */
    private boolean processUserCreation(final Users user, final List<Usermeta> metas) {
        return executeAll(
                () -> saveUserBasicInfo(user),
                () -> saveUserMetas(user, metas)
        );
    }

    /**
     * 处理用户更新流程
     */
    private boolean processUserUpdate(final Users user, final List<Usermeta> metas) {
        return executeAll(
                () -> updateUserBasicInfo(user),
                () -> updateUserMetas(user, metas)
        );
    }

    /**
     * 在事务中删除用户
     */
    private boolean deleteUserInTransaction(final Object userId) {
        return executeAll(
                () -> userService.deleteAllUserMetas(userId),
                () -> userService.deleteById(userId)
        );
    }

    /**
     * 执行所有操作，全部成功返回true
     */
    @SafeVarargs
    private final boolean executeAll(final Supplier<Boolean>... operations) {
        for (final Supplier<Boolean> operation : operations) {
            if (!operation.get()) {
                return false;
            }
        }
        return true;
    }

    // ============ 私有方法：Service层调用封装 ============

    private boolean saveUserBasicInfo(final Users user) {
        return userService.save(user);
    }

    private boolean updateUserBasicInfo(final Users user) {
        return userService.update(user);
    }

    private boolean saveUserMetas(final Users user, final List<Usermeta> metas) {
        return metas == null || metas.isEmpty() ||
                metas.stream().allMatch(meta -> {
                    meta.setUserId(user.getID());
                    return userService.saveUsermeta(meta);
                });
    }

    private boolean updateUserMetas(final Users user, final List<Usermeta> metas) {
        if (metas == null || metas.isEmpty()) {
            return true;
        }
        return metas.stream().allMatch(meta -> {
            if (meta.getUmetaId() == null) {
                return userService.saveUsermeta(meta);
            } else {
                return userService.updateUsermeta(meta);
            }
        });
    }

    // ============ 私有方法：会话管理 ============

    /**
     * 创建用户会话
     */
    private Ret createUserSession(final Users user, final boolean keepLogin,
                                  final String loginIp, final String userAgent) {
        // 计算会话有效期
        final long liveSeconds = keepLogin ? KEEP_LOGIN_SECONDS : DEFAULT_LOGIN_SECONDS;
        final int maxAgeInSeconds = (int) (keepLogin ? liveSeconds : -1);

        // 生成会话信息
        final long loginTime = System.currentTimeMillis();
        final long expireAt = loginTime + (liveSeconds * 1000);
        final String sessionId = StrKit.getRandomUUID();

        // 保存会话到数据库
        final boolean saveSuccess = saveSessionToDatabase(user, sessionId, expireAt, loginIp, userAgent, loginTime);
        if (!saveSuccess) {
            log.error("创建用户会话失败：保存会话到数据库失败，用户ID: %s", user.getID());
            return buildBusinessError(ERROR_SESSION_SAVE_FAILED, "保存会话令牌失败，请联系管理员");
        }

        // 存入缓存
        cache.setCache(Users.loginUserCacheName, sessionId, user);

        log.debug("用户会话创建成功，用户ID: %s, 会话ID: %s, 保持登录: %s",
                user.getID(), StringKit.hideSensitiveInfo(sessionId, 8, 4), keepLogin);

        // 返回登录结果
        return Ret.ok(Users.sessionIdName, sessionId)
                .set(Users.loginUserCacheName, user)
                .set("maxAgeInSeconds", maxAgeInSeconds);
    }

    /**
     * 保存会话到数据库
     */
    private boolean saveSessionToDatabase(final Users user, final String sessionId, final long expireAt,
                                          final String loginIp, final String userAgent, final long loginTime) {
        try {
            // 获取或创建会话元数据
            Usermeta meta = userService.getUserMeta(user.getID(), Usermeta.session_tokens);
            if (meta == null) {
                meta = new Usermeta();
                meta.setUserId(user.getID());
                meta.setMetaKey(Usermeta.session_tokens);
            }

            // 设置会话信息
            meta.setSessionTokens(sessionId, expireAt, loginIp, userAgent, loginTime);

            // 保存到数据库
            return userService.saveOrUpdateUsermeta(meta);

        } catch (Exception e) {
            log.error("保存会话到数据库失败，用户ID: %s", user.getID(), e);
            return false;
        }
    }

    /**
     * 延长会话有效期
     */
    private void extendSessionExpiration(final Users user, final String sessionId) {
        try {
            // 获取会话元数据
            final Usermeta meta = userService.getUserMeta(user.getID(), Usermeta.session_tokens);
            if (meta != null) {
                // 获取当前会话数据
                final Map<String, Object> sessionData = meta.getSessionTokens(sessionId);
                if (sessionData != null) {
                    // 延长过期时间
                    final long newExpiration = System.currentTimeMillis() + TimeUnit.MINUTES.toMillis(SESSION_EXTEND_MINUTES);
                    sessionData.put("expiration", newExpiration);

                    // 更新数据库
                    updateSessionInDatabase(meta, sessionId, sessionData);
                    log.debug("会话有效期延长，用户ID: %s, 会话ID: %s", user.getID(), StringKit.hideSensitiveInfo(sessionId, 8, 4));
                }
            }
        } catch (Exception e) {
            log.warn("延长会话有效期失败，用户ID: %s, 会话ID: %s", user.getID(), StringKit.hideSensitiveInfo(sessionId, 8, 4), e);
        }
    }

    /**
     * 验证数据库中的会话有效性
     */
    private boolean validateSessionInDatabase(final Users user, final String sessionId) {
        try {
            // 获取会话元数据
            final Usermeta meta = userService.getUserMeta(user.getID(), Usermeta.session_tokens);
            if (meta == null) {
                log.debug("会话验证失败：未找到会话元数据，用户ID: %s", user.getID());
                return false;
            }

            // 获取指定会话数据
            final Map<String, Object> sessionData = meta.getSessionTokens(sessionId);
            if (sessionData == null) {
                log.debug("会话验证失败：未找到会话数据，会话ID: %s", StringKit.hideSensitiveInfo(sessionId, 8, 4));
                return false;
            }

            // 检查会话是否过期
            final Long expiration = (Long) sessionData.get("expiration");
            if (expiration == null || System.currentTimeMillis() > expiration) {
                log.debug("会话验证失败：会话已过期，会话ID: %s", StringKit.hideSensitiveInfo(sessionId, 8, 4));
                // 删除过期会话
                removeUserSessionFromDatabase(user, sessionId);
                return false;
            }

            log.debug("会话验证成功，用户ID: %s, 会话ID: %s", user.getID(), StringKit.hideSensitiveInfo(sessionId, 8, 4));
            return true;

        } catch (Exception e) {
            log.error("验证数据库会话有效性失败，用户ID: %s, 会话ID: %s", user.getID(), StringKit.hideSensitiveInfo(sessionId, 8, 4), e);
            return false;
        }
    }

    /**
     * 从数据库删除用户会话
     */
    private void removeUserSessionFromDatabase(final Users user, final String sessionId) {
        try {
            // 获取会话元数据
            final Usermeta meta = userService.getUserMeta(user.getID(), Usermeta.session_tokens);
            if (meta != null) {
                // 删除指定会话
                meta.delSessionTokens(sessionId);
                // 更新数据库
                userService.updateUsermeta(meta);
                log.debug("用户会话从数据库删除，用户ID: %s, 会话ID: %s", user.getID(), StringKit.hideSensitiveInfo(sessionId, 8, 4));
            }
        } catch (Exception e) {
            log.error("从数据库删除用户会话失败，用户ID: %s, 会话ID: %s", user.getID(), StringKit.hideSensitiveInfo(sessionId, 8, 4), e);
        }
    }

    /**
     * 删除其他会话
     */
    private boolean removeOtherSessions(final Usermeta sessionMeta, final String currentSessionId) {
        try {
            // 获取所有会话
            final AssocArray sessions = sessionMeta.getSessionTokens();
            if (sessions == null || sessions.isEmpty()) {
                return true;
            }

            boolean hasChanges = false;

            // 遍历所有会话
            @SuppressWarnings("unchecked")
            final Map<String, Object> sessionMap = (Map<String, Object>) sessions.toLinkedHashMap();
            final Iterator<Map.Entry<String, Object>> it = sessionMap.entrySet().iterator();

            while (it.hasNext()) {
                final Map.Entry<String, Object> entry = it.next();
                final String sessionKey = entry.getKey();
                // 保留当前会话，删除其他会话
                if (!currentSessionId.equals(sessionKey)) {
                    // 从缓存删除
                    cache.removeCache(Users.loginUserCacheName, sessionKey);
                    // 从集合删除
                    it.remove();
                    hasChanges = true;
                    log.debug("删除其他会话，会话ID: %s", StringKit.hideSensitiveInfo(sessionKey, 8, 4));
                }
            }

            // 如果有变更，更新数据库
            if (hasChanges) {
                // 序列化会话数据
                final PHPSerializer serializer = new PHPSerializer();
                final byte[] sessionData = serializer.serialize(sessions);
                sessionMeta.setMetaValue(new String(sessionData));

                // 更新数据库
                final boolean result = userService.updateUsermeta(sessionMeta);
                log.debug("删除其他会话完成，更新数据库结果: %s", result);
                return result;
            }

            return true;

        } catch (Exception e) {
            log.error("删除其他会话失败", e);
            return false;
        }
    }

    // ============ 私有方法：缓存管理 ============

    /**
     * 通过缓存查找用户
     */
    private Users findUserWithCache(final String username) {
        // 构建缓存键
        final String cacheKey = "user_by_name:" + username.toLowerCase();

        // 先从缓存获取
        Users user = cache.getCache(USER_CACHE, cacheKey, null);
        if (user == null) {
            // 缓存未命中，从数据库查找
            user = userService.findUserByLoginOrEmail(username);
            if (user != null) {
                // 加载用户元数据
                loadUserMetaData(user);
                // 放入缓存
                cache.setCache(USER_CACHE, cacheKey, user);
                log.debug("用户信息缓存加载，用户名: %s", StringKit.hideSensitiveInfo(username, 2, 2));
            }
        }
        return user;
    }

    private Users getUserWithCache(final Object userId) {
        return getUserDetail(userId);
    }

    private Page<Users> getCachedUserPage(final String cacheKey, final String countCacheKey, final PageParams pageParams) {
        final List<Users> cachedUsers = cache.getCache(USER_CACHE, cacheKey, null);
        final Long cachedTotalRow = cache.getCache(USER_CACHE, countCacheKey, null);

        if (cachedUsers != null && cachedTotalRow != null) {
            final int totalPage = (int) Math.ceil((double) cachedTotalRow / pageParams.getPageSize());
            return new Page<>(cachedUsers, pageParams.getPageNumber(), pageParams.getPageSize(),
                    totalPage, cachedTotalRow.intValue());
        }
        return null;
    }

    private Page<Users> processAndCacheUserSearchResult(final Page<Users> page, final String cacheKey,
                                                        final String countCacheKey, final String keyword) {
        // 为每个用户加载元数据
        page.getList().forEach(this::loadUserMetaData);

        // 异步缓存结果
        cacheUserPageResult(page, cacheKey, countCacheKey, "缓存用户搜索结果");
        return page;
    }

    private Users processAndCacheUserDetail(final Object userId, final String cacheKey) {
        final Users user = userService.getById(userId);
        if (user != null) {
            loadUserMetaData(user);
            executeAsync(() -> cache.setCache(USER_CACHE, cacheKey, user), "缓存用户详情");
        }
        return user;
    }

    private void cacheUserPageResult(final Page<Users> page, final String cacheKey,
                                     final String countCacheKey, final String taskName) {
        if (page.getList() != null && !page.getList().isEmpty()) {
            executeAsync(() -> {
                cache.setCache(USER_CACHE, cacheKey, page.getList());
                cache.setCache(USER_CACHE, countCacheKey, page.getTotalRow());
            }, taskName);
        }
    }

    /**
     * 加载用户元数据
     */
    private void loadUserMetaData(final Users user) {
        try {
            // 加载指定的元数据键
            final List<Usermeta> metas = userService.getUserMetasByKeys(user.getID(),
                    Usermeta.nickname, Usermeta.first_name, Usermeta.last_name,
                    Usermeta.description, Usermeta.simple_local_avatar, Usermeta.role);

            // 将元数据设置到用户对象中
            for (final Usermeta meta : metas) {
                user.put(meta.getMetaKey(), meta.getMetaValue());
            }
            log.debug("用户元数据加载完成，用户ID: %s, 元数据数量: %s", user.getID(), metas.size());
        } catch (Exception e) {
            log.error("加载用户元数据失败，用户ID: %s", user.getID(), e);
        }
    }

    // ============ 私有方法：登录限制管理 ============

    /**
     * 检查登录是否被限制
     */
    private boolean isLoginLimited(final String username) {
        final String cacheKey = "login_attempts:" + username;
        final Integer attempts = cache.getCache(LOGIN_ATTEMPTS_CACHE, cacheKey, 0);
        return attempts >= MAX_LOGIN_ATTEMPTS;
    }

    /**
     * 记录登录失败
     */
    private void recordLoginFailure(final String username, final String ip) {
        final String cacheKey = "login_attempts:" + username;
        final Integer attempts = cache.getCache(LOGIN_ATTEMPTS_CACHE, cacheKey, 0);
        cache.setCache(LOGIN_ATTEMPTS_CACHE, cacheKey, attempts + 1);
        log.warn("登录失败记录，用户名: %s, IP: %s, 失败次数: %s",
                StringKit.hideSensitiveInfo(username, 2, 2), ip, attempts + 1);
    }

    /**
     * 清理登录失败记录
     */
    private void clearLoginFailureRecords(final String username) {
        cache.removeCache(LOGIN_ATTEMPTS_CACHE, "login_attempts:" + username);
    }

    // ============ 私有方法：密码验证 ============

    /**
     * 检查用户是否活跃
     */
    private boolean isUserActive(final Users user) {
        return user != null && user.getUserStatus() == USER_STATUS_ACTIVE;
    }

    /**
     * 验证密码
     */
    private boolean validatePassword(final String inputPassword, final String storedPassword) {
        try {
            // 从存储的密码中提取盐值
            final String salt = PassKit.getSalt(storedPassword);
            // 使用相同盐值加密输入密码
            final String hashedPassword = PassKit.encrypt(inputPassword, salt);
            // 对比加密结果
            return storedPassword.equals(hashedPassword);
        } catch (Exception e) {
            log.error("密码验证异常", e);
            return false;
        }
    }

    // ============ 私有方法：结果处理 ============

    private Ret handleUserCreationResult(final boolean success, final Users user) {
        if (success) {
            executeAsync(() -> clearUserRelatedCache(user), "清理用户缓存");
            return buildSuccess("创建用户成功", Ret.by("userId", user.getID()));
        } else {
            return buildBusinessError(ERROR_SAVE_FAILED, "创建用户失败");
        }
    }

    private Ret handleUserUpdateResult(final boolean success, final Users newUser, final Users oldUser) {
        if (success) {
            executeAsync(() -> {
                clearUserRelatedCache(newUser);
                triggerUserUpdateEvent(oldUser, newUser);
            }, "用户更新后处理");
            return buildSuccess("更新用户成功", Ret.by("userId", newUser.getID()));
        } else {
            return buildBusinessError(ERROR_SAVE_FAILED, "更新用户失败");
        }
    }

    private Ret handleUserDeletionResult(final boolean success, final Object userId) {
        if (success) {
            executeAsync(() -> {
                clearUserCache(userId);
                triggerUserDeleteEvent(userId);
            }, "用户删除后处理");
            return buildSuccess("删除用户成功", null);
        } else {
            return buildBusinessError(ERROR_SAVE_FAILED, "删除用户失败");
        }
    }

    private Ret handleSessionOperationResult(final boolean success, final Object userId) {
        if (success) {
            executeAsync(() -> clearUserCache(userId), "清理会话缓存");
            return buildSuccess("操作成功", null);
        } else {
            return buildBusinessError(ERROR_SESSION_SAVE_FAILED, "操作失败");
        }
    }

    // ============ 私有方法：缓存清理 ============

    private void clearUserRelatedCache(final Users user) {
        if (user == null) {
            return;
        }
        clearUserCache(user.getID());
        clearUserCache("user_by_name:" + user.getUserLogin().toLowerCase());
    }

    private void clearUserCache(final Object cacheKey) {
        cache.removeCache(USER_CACHE, cacheKey);
        cache.removeCache(USER_STATS_CACHE, cacheKey);
    }

    // ============ 私有方法：事件触发 ============

    private void triggerUserUpdateEvent(final Users oldUser, final Users newUser) {
        executeAsync(() -> logUserChange(oldUser, newUser), "用户更新事件");
    }

    private void triggerUserDeleteEvent(final Object userId) {
        executeAsync(() -> logUserDeletion(userId), "用户删除事件");
    }

    private void logUserChange(final Users oldUser, final Users newUser) {
        final List<String> changes = new ArrayList<>();

        // 检查邮箱变更
        if (!Objects.equals(oldUser.getUserEmail(), newUser.getUserEmail())) {
            changes.add("邮箱: " + StringKit.hideSensitiveInfo(oldUser.getUserEmail(), 3, 3) +
                    " -> " + StringKit.hideSensitiveInfo(newUser.getUserEmail(), 3, 3));
        }

        // 检查显示名称变更
        if (!Objects.equals(oldUser.getDisplayName(), newUser.getDisplayName())) {
            changes.add("显示名称: " + oldUser.getDisplayName() + " -> " + newUser.getDisplayName());
        }

        // 如果有变更，记录变更日志
        if (!changes.isEmpty()) {
            log.info("用户信息变更，用户ID: %s, 变更内容: %s", newUser.getID(), String.join("; ", changes));
        }
    }

    private void logUserDeletion(final Object userId) {
        log.info("用户已被删除，用户ID: %s, 删除时间: %s", userId, new Date());
    }

    // ============ 私有方法：通知和统计 ============

    /**
     * 异步发送欢迎通知
     */
    private void sendWelcomeNotificationAsync(final Users user) {
        executeAsyncWithTimeout(() -> {
            sendWelcomeEmail(user);
            sendSystemWelcomeMessage(user);
            logWelcomeNotification(user);
            return null;
        }, "发送欢迎通知", JwpConstants.ASYNC_TASK_TIMEOUT, TimeUnit.SECONDS);
    }

    /**
     * 发送欢迎邮件
     */
    private void sendWelcomeEmail(final Users user) {
        try {
            // TODO: 实现邮件发送逻辑
            log.info("发送欢迎邮件给: %s, 主题: 欢迎加入我们的系统",
                    StringKit.hideSensitiveInfo(user.getUserEmail(), 3, 3));
        } catch (Exception e) {
            log.error("发送欢迎邮件失败，用户ID: %s", user.getID(), e);
        }
    }

    /**
     * 发送系统欢迎消息
     */
    private void sendSystemWelcomeMessage(final Users user) {
        try {
            final Usermeta welcomeMessage = new Usermeta();
            welcomeMessage.setUserId(user.getID());
            welcomeMessage.setMetaKey("welcome_message");
            welcomeMessage.setMetaValue("欢迎您加入系统！请完善您的个人信息。");
            userService.saveUsermeta(welcomeMessage);
            log.debug("系统欢迎消息已发送，用户ID: %s", user.getID());
        } catch (Exception e) {
            log.error("发送系统欢迎消息失败，用户ID: %s", user.getID(), e);
        }
    }

    /**
     * 记录欢迎通知日志
     */
    private void logWelcomeNotification(final Users user) {
        try {
            final Usermeta notificationLog = new Usermeta();
            notificationLog.setUserId(user.getID());
            notificationLog.setMetaKey("welcome_notification_sent");
            notificationLog.setMetaValue("true");
            userService.saveUsermeta(notificationLog);
            log.debug("欢迎通知日志已记录，用户ID: %s", user.getID());
        } catch (Exception e) {
            log.error("记录欢迎通知日志失败，用户ID: %s", user.getID(), e);
        }
    }

    /**
     * 更新用户登录统计
     */
    private void updateUserLoginStats(final Users user, final String loginIp) {
        executeAsync(() -> {
            try {
                // 记录最后登录时间
                Usermeta lastLoginMeta = userService.getUserMeta(user.getID(), "last_login_time");
                if (lastLoginMeta == null) {
                    lastLoginMeta = new Usermeta();
                    lastLoginMeta.setUserId(user.getID());
                    lastLoginMeta.setMetaKey("last_login_time");
                    lastLoginMeta.setMetaValue(String.valueOf(System.currentTimeMillis()));
                    userService.saveUsermeta(lastLoginMeta);
                } else {
                    lastLoginMeta.setMetaValue(String.valueOf(System.currentTimeMillis()));
                    userService.updateUsermeta(lastLoginMeta);
                }

                // 记录最后登录IP
                Usermeta lastLoginIpMeta = userService.getUserMeta(user.getID(), "last_login_ip");
                if (lastLoginIpMeta == null) {
                    lastLoginIpMeta = new Usermeta();
                    lastLoginIpMeta.setUserId(user.getID());
                    lastLoginIpMeta.setMetaKey("last_login_ip");
                    lastLoginIpMeta.setMetaValue(loginIp);
                    userService.saveUsermeta(lastLoginIpMeta);
                } else {
                    lastLoginIpMeta.setMetaValue(loginIp);
                    userService.updateUsermeta(lastLoginIpMeta);
                }

                // 清理统计缓存
                final String statsCacheKey = "user_login_stats:" + user.getID();
                cache.removeCache(USER_STATS_CACHE, statsCacheKey);

                log.debug("用户登录统计更新完成，用户ID: %s, 登录IP: %s", user.getID(), loginIp);

            } catch (Exception e) {
                log.error("更新用户登录统计失败，用户ID: %s", user.getID(), e);
            }
        }, "更新登录统计");
    }

    // ============ 私有方法：工具方法 ============

    private void updateSessionInDatabase(final Usermeta sessionMeta, final String sessionId, final Map<String, Object> sessionData) {
        try {
            // 获取所有会话
            final AssocArray sessions = sessionMeta.getSessionTokens();
            // 更新指定会话
            sessions.set(sessionId, sessionData);

            // 序列化会话数据
            final PHPSerializer serializer = new PHPSerializer();
            final byte[] sessionBytes = serializer.serialize(sessions);
            sessionMeta.setMetaValue(new String(sessionBytes));

            // 更新数据库
            userService.updateUsermeta(sessionMeta);
            log.debug("数据库会话更新成功，会话ID: %s", StringKit.hideSensitiveInfo(sessionId, 8, 4));
        } catch (Exception e) {
            log.error("更新数据库会话失败，会话ID: %s", StringKit.hideSensitiveInfo(sessionId, 8, 4), e);
        }
    }

    private String generateUserSearchCacheKey(final String keyword, final PageParams pageParams) {
        return String.format("user_search:%s:%d:%d",
                keyword != null ? keyword.hashCode() : "all",
                pageParams.getPageNumber(), pageParams.getPageSize());
    }

    private String generateUserSearchCountCacheKey(final String keyword) {
        return String.format("user_search_count:%s",
                keyword != null ? keyword.hashCode() : "all");
    }

    private String getAuthErrorCode(final String methodName) {
        switch (methodName) {
            case "login":
                return ERROR_INVALID_CREDENTIALS;
            case "register":
                return ERROR_SAVE_FAILED;
            case "destroyOtherSessions":
                return ERROR_SESSION_SAVE_FAILED;
            default:
                return ERROR_SESSION_SAVE_FAILED;
        }
    }

    private String getAuthErrorMessage(final String methodName) {
        switch (methodName) {
            case "login":
                return "登录失败，系统异常";
            case "register":
                return "注册失败，系统异常";
            case "destroyOtherSessions":
                return "登出其他设备失败，系统异常";
            default:
                return "操作失败，系统异常";
        }
    }

    private String getUserErrorCode(final String methodName) {
        switch (methodName) {
            case "createUser":
                return ERROR_SAVE_FAILED;
            case "updateUser":
                return ERROR_SAVE_FAILED;
            case "deleteUser":
                return ERROR_SAVE_FAILED;
            default:
                return ERROR_SAVE_FAILED;
        }
    }

    private String getUserErrorMessage(final String methodName) {
        switch (methodName) {
            case "createUser":
                return "创建用户失败，系统异常";
            case "updateUser":
                return "更新用户失败，系统异常";
            case "deleteUser":
                return "删除用户失败，系统异常";
            default:
                return "操作失败，系统异常";
        }
    }
}